\section{Gherkin Description Language}

While developing software for customers, it is difficult to figure out exactly what they want to be built. Better communication between developers and stakeholders is essential to help avoid this kind of wasted time. One technique that really helps facilitate this communication is the use of concrete examples to illustrate what the software should do, e.g.:

\begin{shaded}
\textit{If a~customer enters a~credit card number that is not exactly 16 digits long, when they try to submit the form, it should be redisplayed with an error message advising them of the correct number of digits.}
\end{shaded}

A developer implementing this feature knows almost everything to be able to start working on the code. Whereas a~stakeholder has a~much clearer idea of what is going to be built.

Using real-world examples to describe the desired behaviour of the system sticks to language and terminology that makes sense to customers. Communication in terms of these examples can really help stakeholders to imagine using the system so they can provide useful feedback and ideas before a~line of code has been written.

Another advantage of using concrete examples is that they are much easier to validate against the running system than vague requirement statements. The challenge with writing good automated acceptance tests is that they need to be readable by not only the computer but also by our customers. This is where Gherkin comes in.

\subsection{Executable Specifications}
Gherkin offers a~lightweight structure for documenting examples of the behaviour stakeholders want, in a~way that it can be easily understood both by stakeholders and a~computer. The primary design goal of Gherkin is human readability, meaning written automated tests can be read like a~documentation~\cite{Wynne2012}:\\

\parbox[b]{\textwidth}{
\textbf{Feature}: Feedback when entering invalid credit card details

In user testing we have seen a~lot of people who made mistakes\\
entering their credit card. We need to be as helpful as possible\\
here to avoid losing users at this crucial stage of the transaction.\\

\textbf{Background}:\\
\textbf{Given} I have chosen some items to buy\\
\textbf{And} I am about to enter my credit card details\\

\textbf{Scenario}: Credit card number too short\\
\textbf{When} I enter a~card number that is only 15 digits long\\
\textbf{And} all the other details are correct\\
\textbf{And} I submit the form\\
\textbf{Then} the form should be redisplayed\\
\textbf{And} I should see a~message advising me of the correct number of digits\\

\textbf{Scenario}: Expiry date invalid\\
\textbf{When} I enter a~card expiry date that is in the past\\
\textbf{And} all the other details are correct\\
\textbf{And} I submit the form\\
\textbf{Then} the form should be redisplayed\\
\textbf{And} I should see a~message telling me the expiry date must be wrong}

\subsection{Format and Syntax}
Gherkin files are saved as plain text, meaning they can be read and edited with simple tools. The structure and meaning is defined by a~set of special keywords:
\textbf{Feature}, \textbf{Background}, \textbf{Scenario}, \textbf{Given}, \textbf{When}, \textbf{Then}, \textbf{And}, \textbf{But}, \textbf{Scenario outline}, \textbf{Examples}.

\subsubsection*{Feature}
Each Gherkin file begins with the \textbf{Feature} keyword. It just provides a~convenient place to put a~summary documentation about the group of tests that follow:\\

\parbox[b]{\textwidth}{
\textbf{Feature}: This is the feature title\\
This is the description of the feature,\\
which can span multiple lines.\\
Everything until the next Gherkin keyword\\
is included in the description.}\\

The text immediately following on the same line as the \textbf{Feature} keyword is the name of the feature, and the remaining lines are its description which can span multiple lines. It is a~place to insert details about who will use the feature, and why, or to put links to a~supporting documentation. In valid Gherkin, a~\textbf{Feature} section must be followed by one of the statements: \textbf{Scenario}, \textbf{Background}, \textbf{Scenario outline}.

\subsubsection*{Scenario}
To actually express the desired behaviour, each feature contains several scenarios. Each scenario is a~single concrete example of how the system should behave in a~particular situation. Each scenario must make sense and possible to be executed independently of any other one.

A feature typically has about 5-20 scenarios describing different examples of how that feature should behave in different circumstances. All scenarios follow the same pattern -- start with a~context, describe an action, and check whether the outcome was expected.

\subsubsection*{Given, When, Then}
In Gherkin, keywords \textbf{Given}, \textbf{When}, and \textbf{Then} are used to identify mentioned parts of the scenario:\\

\parbox[b]{\textwidth}{
\textbf{Scenario}: Successful withdrawal from an account in credit\\
\textbf{Given} I have \$100 in my account \textit{\# the context}\\
\textbf{When} I request \$20 \textit{\# the event}\\
\textbf{Then} \$20 should be dispensed \textit{\# the outcome}}\\

A keyword \textbf{Given} is used to set up the context where the scenario happens, \textbf{When} to interact with the system, and \textbf{Then} to check whether the outcome of that interaction was expected.

\subsubsection*{And, But}
Every line in a~scenario is known as a~step. More steps can be added to each \textbf{Given}, \textbf{When}, or \textbf{Then} section of the scenario using the keywords \textbf{And} and \textbf{But}:\\

\parbox[b]{\textwidth}{
\textbf{Scenario}: Attempt withdrawal using stolen card\\
\textbf{Given} I have \$100 in my account\\
\textbf{But} my card is invalid\\
\textbf{When} I request \$50\\
\textbf{Then} my card should not be returned\\
\textbf{And} I should be told to contact the bank}\\

